/*
 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.util;

/**
 * 进一步提供其元素的总排序的集合。
 * 元素使用它们的自然顺序排序，或者使用通常在创建已排序集时提供的比较器进行排序。
 * 集合的迭代器将按升序元素顺序遍历集合。
 * 还提供了几个额外的操作来利用排序。(此接口是SortedMap的模拟set。)
 *
 * <p>插入到排序集中的所有元素必须实现Comparable接口(或被指定的比较器接受)。
 * 此外,所有这些元素都必须相互可比:e1.compareTo (e2)(或comparator.compare (e1, e2))
 * 不应该抛出一个ClassCastException，对于任何元素e1和e2。
 * 试图违反这一限制将导致出错的方法或构造函数调用抛出一个ClassCastException。
 *
 * <p>请注意，如果要正确地实现set接口，那么由已排序集维护的顺序(无论是否提供显式比较器)必须与equals一致。
 * (参见Comparable接口或Comparator接口，以获得与equals一致的精确定义。)
 * 这是因为Set接口是根据equals操作定义的，但是一个排序的集合使用它的compareTo(或compare)方法执行所有的元素比较，
 * 所以从排序的集合的角度来看，这个方法认为compare相等的两个元素是equals相等的。
 * 排序集的行为是定义良好的，即使它的排序与equals不一致;只是没有遵守Set接口的一般约定。
 *
 * <p>所有通用的排序集实现类都应该提供4个“标准”构造函数:
 * 1)一个void(无参数)构造函数，它创建一个根据其元素的自然顺序排序的空的排序集。
 * 2)一个只有一个比较器类型参数的构造函数，它创建一个根据指定的比较器排序的空的排序集。
 * 3)一个构造函数，该构造函数的参数类型为Collection，它创建一个新的已排序的集合，集合中的元素与它的参数相同，按元素的自然顺序排序。
 * 4)一个只有一个SortedSet类型参数的构造函数，它用与输入排序集相同的元素和顺序创建一个新的排序集。
 *
 * <p>注意:一些方法返回具有限定范围的子集。
 * 这些范围是半开的，也就是说，它们包括它们的低端点，但不包括它们的高端点(如果适用的话)。
 * 如果您需要一个封闭范围(包括两个端点)，并且元素类型允许计算给定值的后继，那么只需请求子范围从lowEndpoint到后继(highEndpoint)。
 * 例如，假设s是一组排序后的字符串。下面的习语获得了一个包含s中从低到高的所有字符串的视图，包括:<pre>
 *   SortedSet&lt;String&gt; sub = s.subSet(low, high+"\0");</pre>
 *
 * 可以使用类似的技术生成一个开放范围(其中不包含端点)。
 * 下面的习惯用法获得了一个包含s中从低到高的所有字符串的视图，排他的:<pre>
 *   SortedSet&lt;String&gt; sub = s.subSet(low+"\0", high);</pre>
 *
 * @param <E> the type of elements maintained by this set
 *
 * @author  Josh Bloch
 * @see Set
 * @see TreeSet
 * @see SortedMap
 * @see Collection
 * @see Comparable
 * @see Comparator
 * @see ClassCastException
 * @since 1.2
 */

public interface SortedSet<E> extends Set<E> {
    /**
     * 返回用于对该集合中的元素排序的比较器，如果该集合使用其元素的自然顺序，则返回null。
     *
     * @return the comparator used to order the elements in this set,
     *         or <tt>null</tt> if this set uses the natural ordering
     *         of its elements
     */
    Comparator<? super E> comparator();

    /**
     * 返回该集合中元素范围从fromElement(包括)到toElement(不包括)的部分的视图。
     * (如果fromElement和toElement相等，则返回的集合为空。)
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * <p>返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     * 
     *
     * @param fromElement low endpoint (inclusive) of the returned set
     * @param toElement high endpoint (exclusive) of the returned set
     * @return a view of the portion of this set whose elements range from
     *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive
     * @throws ClassCastException if <tt>fromElement</tt> and
     *         <tt>toElement</tt> cannot be compared to one another using this
     *         set's comparator (or, if the set has no comparator, using
     *         natural ordering).  Implementations may, but are not required
     *         to, throw this exception if <tt>fromElement</tt> or
     *         <tt>toElement</tt> cannot be compared to elements currently in
     *         the set.
     * @throws NullPointerException if <tt>fromElement</tt> or
     *         <tt>toElement</tt> is null and this set does not permit null
     *         elements
     * @throws IllegalArgumentException if <tt>fromElement</tt> is
     *         greater than <tt>toElement</tt>; or if this set itself
     *         has a restricted range, and <tt>fromElement</tt> or
     *         <tt>toElement</tt> lies outside the bounds of the range
     */
    SortedSet<E> subSet(E fromElement, E toElement);

    /**
     * 返回该集合中元素严格小于toElement部分的视图。
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * <p>返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     *
     * @param toElement high endpoint (exclusive) of the returned set
     * @return a view of the portion of this set whose elements are strictly
     *         less than <tt>toElement</tt>
     * @throws ClassCastException if <tt>toElement</tt> is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if <tt>toElement</tt> does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if <tt>toElement</tt> cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if <tt>toElement</tt> is null and
     *         this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and <tt>toElement</tt> lies outside the
     *         bounds of the range
     */
    SortedSet<E> headSet(E toElement);

    /**
     * 返回该集合中元素大于或等于fromElement的部分的视图。
     * 返回的集合由这个集合支持，所以返回的集合中的变化反映在这个集合中，反之亦然。
     * 返回的集合支持此集合支持的所有可选集合操作。
     *
     * <p>返回的集合将在试图插入超出其范围的元素时抛出IllegalArgumentException。
     *
     * @param fromElement low endpoint (inclusive) of the returned set
     * @return a view of the portion of this set whose elements are greater
     *         than or equal to <tt>fromElement</tt>
     * @throws ClassCastException if <tt>fromElement</tt> is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if <tt>fromElement</tt> does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if <tt>fromElement</tt> cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if <tt>fromElement</tt> is null
     *         and this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and <tt>fromElement</tt> lies outside the
     *         bounds of the range
     */
    SortedSet<E> tailSet(E fromElement);

    /**
     * 返回当前集合中的第一个(最低的)元素。
     *
     * @return the first (lowest) element currently in this set
     * @throws NoSuchElementException if this set is empty
     */
    E first();

    /**
     * 返回当前集合中最后一个(最高的)元素。
     *
     * @return the last (highest) element currently in this set
     * @throws NoSuchElementException if this set is empty
     */
    E last();

    /**
     * 在这个排序集的元素上创建一个Spliterator。
     *
     * <p>Spliterator报告DISTINCT，SORTED，ORDERED。实现应该记录其他特征值的报告。
     *
     * <p>如果排序集的比较器(参见comparator())为空，那么spliterator的比较器
     * (参见java.util.Spliterator.getComparator())必须为空。
     * 否则，spliterator的比较器必须与已排序集的比较器相同，或者施加相同的总排序。
     *
     * 
     * <p>The default implementation creates a
     * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
     * from the sorted set's {@code Iterator}.  The spliterator inherits the
     * <em>fail-fast</em> properties of the set's iterator.  The
     * spliterator's comparator is the same as the sorted set's comparator.
     * 
     * 默认实现从排序集的迭代器创建一个后期绑定spliterator。
     * spliterator继承了set的迭代器的快速失效属性。spliterator的比较器与排序集的比较器是相同的。
     * <p>
     * The created {@code Spliterator} additionally reports
     * {@link Spliterator#SIZED}.
     *
     * 
     * The created {@code Spliterator} additionally reports
     * {@link Spliterator#SUBSIZED}.
     *
     * @return a {@code Spliterator} over the elements in this sorted set
     * @since 1.8
     */
    @Override
    default Spliterator<E> spliterator() {
        return new Spliterators.IteratorSpliterator<E>(
                this, Spliterator.DISTINCT | Spliterator.SORTED | Spliterator.ORDERED) {
            @Override
            public Comparator<? super E> getComparator() {
                return SortedSet.this.comparator();
            }
        };
    }
}
